Registration flow

In this example, we will use Facebook for simplicity. But note that flow is very similar for other providers (like Google+ and Twitter)

1. GateIn Portal login page will have buttons for login with Facebook, Google or Twitter. It will have only providers, which you configured. See screenshot with enabled authentication for Facebook and Google+:

   
   Sign in dialog with enabled Facebook and Google

2. After click to Sign in with Facebook button, user will be redirected to Facebook site

   1. He needs to authenticate to Facebook if not already authenticated

   2. Facebook will display authorization screen. Note that required privileges (scopes) are those, which you configured in configuration.properties. Usually it's sufficient to cover only scopes to obtain email and user profile informations. When you add more privileges, your application can do more things, but on the other hand, you have smaller chance that your users will confirm authorization screen. (For example: It's not good idea to request publish message on FB wall privilege, if you want to use your GateIn Portal just for registration/authentication of user)

3. User confirmed authorization screen and he will be redirected back to GateIn Portal. More accurately, he will be redirected to URI which you configured as "Redirect URI" during registration process of your application. In case of Facebook, the URL will look like http://server.local.network.com:8080/portal/facebookAuth (Assuming that your GateIn Portal is running on host server.local.network.com)

4. GateIn Portal will display registration dialog with prepopulated values from Facebook.

   
   Registration dialog with prepopulated values from Facebook

5. User will finish his registration and then he will be directly signed into GateIn Portal.

Note that from this point, user joseph.breburda will be treated as normal user of GateIn Portal. So portal administrator will see him in list of users in GateIn Portal UI and he can add him to more groups (By default he will be only in /platform/users group). User registered through Facebook will have two additional properties saved as part of his UserProfile:

• Facebook username - This could be same like GateIn Portal username, however it's not necessary. It is used for mapping of GateIn Portal identity to Facebook identity, which is needed in Login flow and other places. So it provides information like: GateIn Portal user joseph is mapped to Facebook user joseph.breburda. In GateIn Portal there is restriction that Facebook username needs to be unique, so we can't have 2 GateIn Portal users with same Facebook username.

• Facebook access token - This is needed for social portlets, so they can use accessToken to retrieve needed information from Facebook. For example: You can have portlet for displaying content of Facebook wall of particular user. More example about portlets is here .

  Access token is saved in Picketlink IDM in encoded form with usage of symmetric encryption. Codec component is leveraged to encode/decode access token.

Those attributes are tracked for each OAuth Provider, so single GateIn Portal user linked with both Facebook and Google will have: Facebook username, Facebook accessToken, Google username, Google accessToken

Login flow

This flow is used if GateIn Portal username is already connected with Facebook username (For example: GateIn Portal user joseph is connected with Facebook user joseph.breburda)

1. Steps 1-3 are same like for Registration flow. Let's assume that user authenticated to Facebook as joseph.breburda is mapped to portal user joseph

2. User is directly logged into GateIn Portal as joseph because GateIn Portal already knows that username joseph belongs to authenticated Facebook user joseph.breburda

Connecting another social provider to existing account

Let's assume that portal user joseph is already linked and authenticated to GateIn Portal through Facebook. But he wants to link his GateIn Portal account with other OAuth providers (like Google+ and Twitter) so in the future, he could be able to login into GateIn Portal through Google+ or Twitter. He may also want it because he wants to use portlets for integration with Facebook,Google+ and Twitter.

In UserInfo screen, there is another tab with "Social networks". Here user can:

• Link his GateIn Portal account to other providers like Google+ or Twitter

• Unlink existing providers, so his GateIn Portal username won't be connected to Facebook anymore and his Facebook accessToken will be invalidated

  
  Social networks tab

Administration

GateIn Portal administrator has possibility to unlink users from social account. They have also possibility to link their Facebook (Google+, Twitter) username with their GateIn Portal accounts. In this case accounts will be linked, but access token of user doesn't exists. So user needs to authenticate through Social network to have access token available to access social info in portlets.